Lấy tỷ giá lịch sử

Truy vấn lịch sử tỷ giá của một cặp tiền tệ để Merchant có thể đối chiếu và phân tích các báo giá quá khứ. Tỷ giá lịch sử được lưu giữ ít nhất 2 tháng.

API hỗ trợ hai chế độ:

• Một ngày (type = 1) — trả về các ảnh chụp tỷ giá được ghi lại vào một ngày cụ thể.
• Khoảng ngày (type = 2) — trả về tỷ giá trung bình hàng ngày cho mỗi ngày trong khoảng ngày.

Đường dẫn

• URL: /cb-core/api/v1/fx/get-historical-rate
• Method: POST
• Mô tả: Truy vấn lịch sử tỷ giá của một cặp tiền tệ.

Request

Bảng Request

Tham số	Loại dữ liệu	Bắt buộc	Mô tả
request_id	string(50)	Có	Mã duy nhất định danh request. Định dạng gợi ý: MerchantCode + BK + YYYYMMDD + UniqueId
request_time	string(19)	Có	Thời gian Merchant gửi request. Định dạng: YYYY-MM-DD HH:MM:SS
merchant_code	string(20)	Có	Mã merchant được Baokim cung cấp trước khi tích hợp
type	int(1)	Có	Chế độ truy vấn. 1: ảnh chụp tỷ giá vào một ngày duy nhất. 2: tỷ giá trung bình hàng ngày trong khoảng ngày
from_currency	string(10)	Có	Mã ngoại tệ (ví dụ USD). Chỉ cho phép một mã tiền tệ
to_currency	string(10)	Có	Mã tiền tệ báo giá (ví dụ VND). Chỉ cho phép một mã tiền tệ
date	string(21)	Có	Khi type = 1: một ngày duy nhất YYYY-MM-DD. Khi type = 2: khoảng ngày start_date,end_date, ví dụ 2026-04-01,2026-06-01

Ví dụ Request — type = 1

{
  "request_id": "MERCHANT1234BK202606054",
  "request_time": "2026-06-05 10:15:30",
  "merchant_code": "MERCHANT1234",
  "type": 1,
  "from_currency": "USD",
  "to_currency": "VND",
  "date": "2026-06-01"
}

Ví dụ Request — type = 2

{
  "request_id": "MERCHANT1234BK202606055",
  "request_time": "2026-06-05 10:15:30",
  "merchant_code": "MERCHANT1234",
  "type": 2,
  "from_currency": "USD",
  "to_currency": "VND",
  "date": "2026-04-01,2026-06-01"
}

Response

Bảng Response

Tham số	Loại dữ liệu	Bắt buộc	Mô tả
response_code	int(4)	Có	Mã kết quả từ Baokim, theo bảng Mã lỗi
response_message	string(200)	Có	Mô tả mã kết quả
merchant_code	string(20)	Có	Mã merchant được Baokim cung cấp trước khi tích hợp
data	Object	Có	Kết quả tỷ giá lịch sử

Cấu trúc Object Data (bên trong data)

Tham số	Loại dữ liệu	Mô tả
currency_pair	string(10)	Cặp tiền tệ ở định dạng BASE/QUOTE (ví dụ USD/VND)
type	int(1)	Chế độ truy vấn được phản ánh lại (1 hoặc 2)
result	Array of Objects	Danh sách các điểm tỷ giá lịch sử

Cấu trúc mảng result

Tham số	Loại dữ liệu	Mô tả
timestamp	string(19)	Khi type = 1: thời gian ảnh chụp YYYY-MM-DD HH:MM:SS. Khi type = 2: ngày YYYY-MM-DD
bid	decimal(18,4)	Tỷ giá mua tại điểm đó (trung bình hàng ngày khi type = 2)
ask	decimal(18,4)	Tỷ giá bán tại điểm đó (trung bình hàng ngày khi type = 2)

Ví dụ Response — type = 1

{
  "response_code": 200,
  "response_message": "Thành công",
  "merchant_code": "MERCHANT1234",
  "data": {
    "currency_pair": "USD/VND",
    "type": 1,
    "result": [
      { "timestamp": "2026-06-01 08:00:00", "bid": 26400.0000, "ask": 26460.0000 },
      { "timestamp": "2026-06-01 09:00:00", "bid": 26430.0000, "ask": 26490.0000 },
      { "timestamp": "2026-06-01 10:05:00", "bid": 26445.0000, "ask": 26505.0000 },
      { "timestamp": "2026-06-01 15:00:00", "bid": 26460.0000, "ask": 26520.0000 }
    ]
  }
}

Ví dụ Response — type = 2

{
  "response_code": 200,
  "response_message": "Thành công",
  "merchant_code": "MERCHANT1234",
  "data": {
    "currency_pair": "USD/VND",
    "type": 2,
    "result": [
      { "timestamp": "2026-04-01", "bid": 26200.1500, "ask": 26260.4500 },
      { "timestamp": "2026-04-02", "bid": 26250.1000, "ask": 26310.2000 },
      { "timestamp": "2026-04-03", "bid": 26255.2341, "ask": 26315.6300 }
    ]
  }
}

Mã lỗi

Mã Response	Thông báo Response
200	Thành công
101	Lỗi hệ thống
110	Mã merchant không hợp lệ
120	Signature không hợp lệ
404	Cặp tiền tệ không được hỗ trợ
422	Lỗi xác thực
429	Quá nhiều yêu cầu